1 Introduction

• You can download the workshop material on GitHub .

• Don’t hesitate to comment (new issues), or request changes (pull request) on GitHub .

• Follow the .html (web browser) and the .Rmd (R studio) documents. Try and experiment.

• ~2 hours: Introduction and practice

• ~15 minutes: pause

• ~1 hour: other formats (.docx, .pdf, and others). Workshop here

• ~15 minutes: shiny. Workshop here

2 Markdown

• Markdown is a lightweight markup language with plain text formatting syntax (Easy-to-read, easy-to-write plain text format). It is designed so that it can be easily converted to HTML and many other formats (e.g. PDF, MS Word, .docx).

• Like other markup languages (e.g. HTML and Latex), it is completely independent from R.

• Typically, file have the extension .md.

• Look at this example. Examine the html render (GitHub automatically interprets .md files) and raw file.
  

3 R Markdown

• An extension of the markdown syntax that enables R code to be embedded and executed.

• Generate fully reproducible reports in different static and dynamic output formats.

• Most of these packages are maintained by the R studio team (https://rmarkdown.rstudio.com/, Yihui Xie)

• Plain text files that typically have the file extension .Rmd.

• So, how does it work:

  • Write text & code in R studio.

  • Knit: The R package rmarkdown feeds the .Rmd file to the R package knitr.

  • knitr executes code and creates a new markdown (.md) document which includes the code and output.

  • Subsequently tranformed into .html/.tex/.docx by pandoc. (Note that .tex files need to be transformed by pdflatex into .pdf files. We’ll come back to that later.)

  • Pandoc is an universal document converter, independent of R.

  • By default, Rstudio comes with rmarkdown, knitr, and pandoc (but not pdflatex).

  • When you click the Knit button (top left), a document will be generated that includes both content as well as the output of R code within the document. You can also use the render() function.

4 R markdown syntax

• Markdown provides an easy way to make standard types of formatted text, like:

  • italics (*text*) or italics (_text_)

  • bold (**bold**)

  • backslash (\) to interpret a special characters as character

  • “# and space” at the beginning of line for a header level (6 levels, # to ######)

  • bold italic (_**bold italic**_)

  • links ([links](https://www.rmarkdown.rstudio.com))

  • (<!–comments–>)

  • Two spaces or two carriage return for a newline character

  • list (first element using “* and space”, then “idented (tab or 2 spaces) * and space”)
    • item 1a
    • item 1b

  • *** for an horizontal line

  • quoted text (`quoted text`)

> Quoted text: 1st way
> more quoted text
> still more quoted text

Quoted text: 1st way
more quoted text
still more quoted text

`Quoted text: 2nd way`
`more quoted text`
`still more quoted text`

Quoted text: 2nd way
more quoted text
still more quoted text

```
text: 3rd way
quoted text
more quoted text
```

Quoted text: 3rd way    
more quoted text         
still more quoted text        

• Tables

Species | Counts
——— | —–
H. sapiens | 24
M. musculus | 442

• The cheatsheet is your friend.

5 Header

---  
title: "Rmarkdown"  
author: "Sebastien Renaut"  
date: '2018-03-12'  
output: html_document  
---  

• Header, metadata, YAML, YAML Ain’t Markup Language (https://en.wikipedia.org/wiki/YAML#History_and_name) ?

• Header specifies configurations (what kind of document will be created, and the options chosen).

• It is not required (defaults then apply).

• It uses Python-style indentation to specify certain options.

• Many options possible depending what type of document you are generating. See below for some examples.

• Note that some options can be specified either for the whole document (in the header), the code chunks, or both (chunks options supersede header). More on code chunks later.

---  
title: "Rmarkdown"  
author: "Sebastien Renaut"  
date: "March 06, 2019"   
output: 
 html_document:  
   highlight: tango  
   number_sections: T  
   theme: cerulean 
   toc: yes  
   toc_depth: 3  
---  

# Preface {-}

6 Code chunks

• The real power of R Markdown comes from mixing markdown syntax with chunks of code.

• A code chunk is intepreted by knitr. It works essentially the same as the R syntax we are familiar with.

• A main code chunks may look like this:

```{r example, include = T, message = T, warning=T, echo = F, fig.cap="A figure of random points"}  
#Running some R code.
x = rexp(1000)  
min(x)  
max(x)  
plot(x)  
```    

## [1] 0.0002072449

## [1] 9.006855

A figure of random points

• On the 1st line, I specify that I will run the R programming language.

• Then, I give the chunk a UNIQUE name and specify options.

• There are a large number of chunk options in knitr documented here.

• Here are common options:

  • include = FALSE: Code and results will NOT appear in the finished file. Code is still interpreted, and the results can be used by other chunks.

  • echo = F prevents code, but not results from appearing in the finished file. This is a useful way to embed figures.

  • message = F prevents messages that are generated by code from appearing in the finished file.

  • warning = F prevents warnings that are generated by code from appearing in the finished file.

  • fig.cap = "..." adds a caption to graphical results.

  • fig.width=..., fig.height=... can also change figure width/heigth.

• By default R studio creates a Global Options code chunk. Let’s examine this chunk:

```{r setup, include=FALSE}  
knitr::opts_chunk$set(echo = TRUE)  
```  

• see cheat sheet for more info.

• Note that you also run inline code using the using the ` ` symbols and specifying the programming language. For example, ` r 10+5 ` would be processes as 15.

```{bash, echo = F}
ls -1 | head -3
```

## rmarkdown_main.Rmd
## rmarkdown_main.html
## rmarkdown_main.log

```{python, echo = F}
x = "hello python!"
print(x.split(' '))
```

## ['hello', 'python!']

```{perl, echo = F}
print "Hello perl!";
```

## Hello perl!

7 Math symbols

Mathematical material is set off by the use of single dollar-sign characters (similar as in the LaTeX typesetting language).

• So to write \(E = mc^{2}\), you’d write: $E = mc^{2}$

• \(\sum_{i=1}^n ASV\)

• \(F_{(1,69)}\) = 1.27, p-value=0.26

• \(A = \pi*r^{2}\)

• \(\sqrt{b^2 - 4ac}\)

• If you wish to use a dollar sign, you need to preface it with a back-slash \(E = mc^{2}\) versus $E = mc^{2}$

• The use of double dollars quote allows for displayed formulas (centered). \[\sqrt{b^2 - 4ac}\]

• See more example equations from this McGill math R markdown tutorial.

8 Include pictures & figures

There are several ways to include figures.

knitr

Images can also be interpreted by knitr as below:

```{r graphic_example, out.width = "20%", fig.cap = "rosa_banksiae", echo = F,fig.align = "center"}  
knitr::include_graphics("../figures/rosa_banksiae.JPG")  
```

rosa_banksiae.JPG

```{r roses, out.width = "50%",echo = F,out.extra='style="float:right; padding:10px"'}
knitr::include_graphics("../figures/rosa_banksiae.JPG")  
```

```{r another example, echo = F, message = F}
library(ggplot2)
mtcars_ggplot = ggplot(mtcars, aes(x=wt, y=mpg)) + 
geom_point() + geom_smooth()
mtcars_ggplot
```

```{r out.width=c('50%', '50%'), fig.show='hold',echo=F}
mtcars_ggplot
plot(rnorm(10))
```

## `geom_smooth()` using method = 'loess' and formula 'y ~ x'

9 Including Tables

• By default, R Markdown displays data frames and matrices as they would be in the R terminal (in a monospaced font).

• You can use the knitr::kable function for additional formatting, as in the .Rmd file below.

#Default R printout (ugly)
print(head(mtcars))

##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

#With kable function from knitr (better looking)
knitr::kable(head(mtcars),digits =1,caption = "A motorcars table")

10 References

csl: peerj.csl  
bibliography: test_library.bib  

@article{altschul1997gapped,
  title={Gapped BLAST and PSI-BLAST: a new generation of protein database search programs},
  author={Altschul, Stephen F and Madden, Thomas L and Sch{\"a}ffer, Alejandro A and Zhang, Jinghui and Zhang, Zheng and Miller, Webb and Lipman, David J},
  journal={Nucleic acids research},
  volume={25},
  number={17},
  pages={3389--3402},
  year={1997},
  publisher={Oxford University Press}
}

11 Cheatsheets and help

• Lessons

• Book
  • This is a great reference. In addition, it is (of course) written in R markdown and publicly available on GitHub. As such, if you see something you want to reproduce, go see how it was written in the .Rmd version!

• Cheatsheet (newer - longer)

• Pimp my Rmd

• Stack Overflow

12 References

(Note that references below are generated automatically, except for the footnote.)